/*============================================================================*/
/*                                                                            */
/*  FILE       : statemc.h                                                    */
/*  CONTENTS   : Contains PC support for NextMove state machine               */
/*----------------------------------------------------------------------------*/
/*    $Archive:: /Software/mbapi/release/include/dprio/STATEMC.H             $*/
/*   $Revision:: 220                                                         $*/
/*----------------------------------------------------------------------------*/
/*  VISIBILITY : Public                                                       */
/*               Copyright (c) 1997 Motionbase PLC                            */
/*               All rights reserved.                                         */
/*----------------------------------------------------------------------------*/
/*  HISTORY    :                                                              */
/*                                                                            */
/*    Date     Author    Description                                          */
/*  10/12/97     KG      Created                                              */
/*============================================================================*/
#ifndef _STATEMC_H_
#define _STATEMC_H_

#ifdef __cplusplus
extern "C" {
#endif

/*============================================================================*/
/* INCLUDES                                                                   */
/*============================================================================*/
#include "platform.h"                  /* TPlatformPositionType, ...          */
/*============================================================================*/
/* MACROS                                                                     */
/*============================================================================*/

/*============================================================================*/
/* TYPEDEFS                                                                   */
/*============================================================================*/
/*----------------------------------------------------------------------------*/
/* Define a common function type that will be called to handle each state.    */
/* stateChanged is non-zero to indicate that the state machine state has      */
/* changed since the last call.                                               */
/*----------------------------------------------------------------------------*/
typedef VOID FAR TStateHandlerFunction (TStateMachineState state,
                                        BYTE stateChanged);

/*============================================================================*/
/* FUNCTION PROTOTYPES                                                        */
/*============================================================================*/
/*----------------------------------------------------------------------------*/
/* initialiseStateMachine                                                     */
/* Downloads code to NextMove and starts the state machine running.           */
/*                                                                            */
/* Args:                                                                      */
/* nmAddress     - the PC I/O address at which NextMove is installed          */
/* pCoffFilePath - pointer to string that holds path to .OUT file to download */
/* pPlatform     - pointer to structure that holds description of MDU and     */
/*                 actuators.                                                 */
/*                                                                            */
/* Return:                                                                    */
/* erSUCCESS                                                                  */
/* erINVALID_HANDLE                                                           */
/* erCARD_NOT_FOUND                                                           */
/* erBAD_BOOT_DEVICE                                                          */
/* erBAD_NEXTMOVE_TYPE                                                        */
/* erTIMEOUT                                                                  */
/* erNOT_RUNNING                                                              */
/* erINITIALISING                                                             */
/* erCANNOT_OPEN_FILE                                                         */
/* erINVALID_FORMAT                                                           */
/* erINVALID_ACTUATOR_INDEX                                                   */
/*----------------------------------------------------------------------------*/
CCONV INT initialiseStateMachine (INT nmAddress,
                                  CHAR FAR* pCoffFilePath,
                                  TPlatform FAR* pPlatform,
                                  FLOAT stateMachinePeriod);

/*----------------------------------------------------------------------------*/
/* serviceStateMachine                                                        */
/* Reads current status of NextMove state machine, and calls appropriate      */
/* state handler functions installed by setStateMachineHandler.               */
/* If NextMove is not ready for servicing the function returns 0.             */
/*                                                                            */
/* Args:                                                                      */
/* pState        - where to store the current state                           */
/* pStateChanged - wher to store indication that the state has changed since  */
/*                 function was last called.                                  */
/*                                                                            */
/* Return:                                                                    */
/* 0 - the state machine did not require servicing.                           */
/* 1 - the state machine has been serviced.                                   */
/*----------------------------------------------------------------------------*/
CCONV BYTE serviceStateMachine (TStateMachineState FAR* pState,
                                BYTE FAR* pStateChanged);

/*----------------------------------------------------------------------------*/
/* setStateMachineHandler                                                     */
/* Assigns a handler function to a platform control mode.                     */
/*                                                                            */
/* Args:                                                                      */
/* sms      - the state machine state                                         */
/* pHandler - the handler associated with the control mode                    */
/*                                                                            */
/* Return:                                                                    */
/* VOID                                                                       */
/*----------------------------------------------------------------------------*/
CCONV VOID setStateMachineHandler (TStateMachineState sms,
                                   TStateHandlerFunction FAR* pHandler);

/*----------------------------------------------------------------------------*/
/* shutdownStateMachine                                                       */
/* Returns the platform to parked position and resets NextMove.               */
/*                                                                            */
/* Args:                                                                      */
/* None                                                                       */
/*                                                                            */
/* Return:                                                                    */
/* erSUCCESS                                                                  */
/*----------------------------------------------------------------------------*/
CCONV INT shutdownStateMachine (VOID);

/*----------------------------------------------------------------------------*/
/* stateDescriptor                                                            */
/* Returns a string associated with the state passed.                         */
/*                                                                            */
/* Args:                                                                      */
/* state - the state machine state for which a descriptor is required.        */
/*                                                                            */
/* Return:                                                                    */
/* pointer to string or null if state invalid                                 */
/*----------------------------------------------------------------------------*/
CCONV const CHAR* stateDescriptor(TStateMachineState state);

#ifdef __cplusplus
} /* extern "C" */
#endif

#endif /* _STATEMC_H_ */
/*============================================================================*/
/* END OF FILE                                                                */
/*============================================================================*/
